<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>getgrnam</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_005_563">&nbsp;</a>NAME</h4><blockquote>
getgrnam, getgrnam_r - search group database for a name
</blockquote><h4><a name = "tag_000_005_564">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="systypes.h.html">sys/types.h</a>&gt;
#include &lt;<a href="grp.h.html">grp.h</a>&gt;

struct group *getgrnam(const char *<i>name</i>);
int getgrnam_r(const char *<i>name</i>, struct group *<i>grp</i>, char *<i>buffer</i>,
    size_t <i>bufsize</i>, struct group **<i>result</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_005_565">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>getgrnam()</i>
function searches the group database for an entry with a matching
<i>name</i>.
<p>
The
<i>getgrnam()</i>
interface need not be reentrant.
<p>
The
<i>getgrnam_r()</i>
function updates the
<b>group</b>
structure pointed to by
<i>grp</i>
and stores a pointer to that structure
at the location pointed to by
<i>result.</i>
The structure contains an entry
from the group database with a matching
<i>gid</i>
or
<i>name</i>.
Storage referenced by the group structure is allocated
from the memory provided with the
<i>buffer</i>
parameter, which is
<i>bufsize</i>
characters in size.
The maximum size needed for this buffer can be determined with the
{_SC_GETGR_R_SIZE_MAX}
<i><a href="sysconf.html">sysconf()</a></i>
parameter.
A NULL pointer is returned at the location pointed to by
<i>result</i>
on error or if the requested entry is not found.
</blockquote><h4><a name = "tag_000_005_566">&nbsp;</a>RETURN VALUE</h4><blockquote>
The
<i>getgrnam()</i>
function returns a pointer to a
<b>struct group</b>
with the structure defined in
<i><a href="grp.h.html">&lt;grp.h&gt;</a></i>
with a matching entry if one is found.
The
<i>getgrnam()</i>
function returns a null pointer if either the requested entry was
not found,
or an error occurred.
On error,
<i>errno</i>
will be set to indicate the error.
<p>
The return value may point to a static area which is overwritten
by a subsequent call to
<i><a href="getgrent.html">getgrent()</a></i>,
<i><a href="getgrgid.html">getgrgid()</a></i>
or
<i>getgrnam()</i>.
<p>
If successful, the
<i>getgrnam_r()</i>
function returns zero.
Otherwise, an error number is returned to indicate the error.
</blockquote><h4><a name = "tag_000_005_567">&nbsp;</a>ERRORS</h4><blockquote>
The
<i>getgrnam()</i>
function may fail if:
<dl compact>

<dt>[EIO]<dd>
An I/O error has occurred.

<dt>[EINTR]<dd>
A signal was caught during
<i>getgrnam()</i>.

<dt>[EMFILE]<dd>
{OPEN_MAX} file descriptors are currently open in the calling process.

<dt>[ENFILE]<dd>
The maximum allowable number of files is currently open in the
system.

</dl>
<p>
The 
<i>getgrnam_r()</i>
function may fail if:
<dl compact>

<dt>[ERANGE]<dd>
Insufficient storage was supplied via
<i>buffer</i>
and
<i>bufsize</i>
to contain the data to be referenced by the resulting
<b>group</b>
structure.

</dl>
</blockquote><h4><a name = "tag_000_005_568">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_005_569">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
Applications wishing to check for error situations should set
<i>errno</i>
to 0 before calling
<i>getgrnam()</i>.
If
<i>errno</i>
is set on return, an error occurred.
</blockquote><h4><a name = "tag_000_005_570">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_005_571">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="endgrent.html">endgrent()</a></i>,
<i><a href="getgrgid.html">getgrgid()</a></i>,
<i><a href="grp.h.html">&lt;grp.h&gt;</a></i>,
<i><a href="limits.h.html">&lt;limits.h&gt;</a></i>,
<i><a href="systypes.h.html">&lt;sys/types.h&gt;</a></i>.
</blockquote><h4>DERIVATION</h4><blockquote>
<i>getgrnam()</i> derived from System V Release 2.0.
<P>
<i>getgrnam_r()</i> derived the POSIX Threads Extension (1003.1c-1995).
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>

